HAL DMA migration: List of applicable concepts

This section provides information about the HAL DMA applicable architecture concepts.

Concepts for DMA

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate init and config functions: HAL_DMA_Init(): initializes the handle and links it to a DMA channel instances. HAL_DMA_SetConfigDirectXfer_xxx/ HAL_DMA_SetConfigLinkedListXfer: Direct transfer configuration functions and Linked list xfer configuration function.
Removal and conversion of init structure to configuration structure	The init structure DMA_InitTypeDef has been removed from the handle and converted into configuration structures for direct transfer and linked list transfer.
Renaming of the handle structure	The handle structure has been renamed to hal_dma_handle_t
Renaming unitary init structures	Unitairy init structures have been renamed to use the _t suffix instead of _TypeDef. For example : DMA_DataHandlingConfTypeDef has been renamed to hal_dma_data_handling_config_t.
Unitary configuration APIs	New APIs are available to get and set DMA features.
Introduction of HAL user data set/get APIs	Two functions to set and get user data are available: HAL_DMA_SetUserData and HAL_DMA_GetUserData.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each DMA event. These functions are used to register callback functions for different DMA events.
HAL implementation with LL inline functions	HAL DMA APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL DMA define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL DMA driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The DMA state machine is reworked to ensure transitions of the peripheral functional states.
Revised and optimized HAL API status returns	The HAL DMA functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	The HAL error handling mechanisms have been redesigned to improve the detection, reporting, and handling of errors. This provides more detailed and consistent error information.
New APIs for filtering optional asynchronous process interrupts	New HAL DMA transfer APIs with interrupt filtering capabilities have been introduced, such as HAL_DMA_StartDirectXfer_IT_Opt() and HAL_DMA_StartLinkedListXfer_IT_Opt().
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL DMA driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macro.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL DMA header file remains and all macros, define statements, and functions from hal_dma_ex.h have been moved to hal_dma.h.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including DMA instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Move Queuing/Linked List Logical Services into a Standalone HAL Queuing Driver	This concerns the HAL Q driver (stm32tnxx_hal_q.h): queue creation is now supported directly by this dedicated driver, rather than being implemented within the HAL DMA layer.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL DMA enums and struct start with hal_dma.

Other HAL DMA changes

Concept	Consideration
Unify initialization and configuration sequence for legacy and linked-list transfers.	The same user sequence need to be adopted to perform legacy and linked-list configuration. Reduces footprint and complexity within PPP module. Init() SetConfig()
DMA linked-list features are available under USE_HAL_DMA_LINKEDLIST compilation switch.	In order to benefit from the HAL DMA linked-list feature, users need to set the USE_HAL_DMA_LINKEDLIST compilation switch to one in the HAL configuration file.
A new sequence is needed to create a linked-list using the HAL Q and associate it to the DMA instance using the dedicated APIs.	Introduce a new HAL Q driver that enables linked-list creation and reworks the association between HAL DMA and linked lists.
Rework FIFO API.	Retain the HAL_DMA_GetFifoData() API to retrieve only the remaining data in the FIFO. Introduce the HAL_DMA_GetRemainingData() API to retrieve the remaining transfer data (including FIFO, BNDT, and BRC). For legacy transfers, this API returns the remaining data for the entire transfer. For linked-list transfers, it returns the remaining data for the current DMA node.
Rework hal_dma_repeat_block_config_t structure to simplify structure usage.	Simplify the configuration of block and burst offset values, as well as jump direction parameters.. Users now specify the size and increment direction explicitly instead of providing signed offset values.
Add weak callbacks (Default) to avoid checking on callbacks pointer after each call within the HAL_DMA_IRQHandler().	Weaks callbacks are affected to handle callbacks within HAL_DMA_Init() then user can customize specific callbacks through HAL_DMA_xxxRegisterCallback(). Unlike other HAL PPP modules that support callback registration, HAL DMA callbacks are not controlled by the USE_HAL_DMA_REGISTER_CALLBACKS compilation flag. These callbacks are always available for internal PPP register process callbacks.
Rework DMA transfer functions parameter size.	For certain series, the last parameter of the DMA start API in both HAL1 and HAL2 indicates the data size in bytes. For other series, in HAL1, the last parameter of the DMA start API specifies the data size as the number of beats, which depends on the source data size. For example, if the source data size is a word, the parameter represents the number of words. In HAL2, for all series, the direct transfer function interprets the data size parameter as the size in bytes. Therefore, when transitioning from HAL1 to HAL2 for these series, users must multiply the data size (in beats) by the source data size to convert it into bytes.
Rework the DMAMUX synchronization API.	HAL_DMAEx_ConfigMuxSync() has been renamed to HAL_DMA_DMAMUX_SetConfigSynchro(). HAL_DMA_MuxSyncConfigTypeDef has been renamed to hal_dma_dmamux_synchro_config_t. request_number has been renamed to nbr_of_request. Synchronization source enumeration items have been renamed . Example: HAL_DMA_DMAMUX1_SYNC_XXX has been renamed to HAL_DMA_DMAMUX1_SYNCHRO_XXX. HAL_DMA_DMAMUX_GetConfigSynchro() has been introduced to to retrieve the synchro config. Three APIs have been introduced to enable, disable, and query the enable state of the synchronization feature. Three APIs have been introduced to enable, disable, and query the enable state of the event generation feature. sync_enable has been removed from the synchronization configuration structure. event_enable has been removed from the synchronization configuration structure.
Rework DMAMUX request generator API.	HAL_DMA_DMAMUX_SetConfigRequestGenerator has been renamed to HAL_DMAEx_ConfigMuxRequestGenerator. request_number has been renamed to nbr_of_request. HAL_DMA_DMAMUX_GetConfigRequestGenerator() has been introduced to retrieve the request generator configuration. Three APIs have been introduced to enable, disable, and query the enable state of the request generator feature.